Document Nexus with Multi-Cluster Replication for self-hosted by stephanos · Pull Request #4906 · temporalio/documentation

stephanos · 2026-07-17T01:06:43Z

WISOTT

Documents how Nexus Operation completion callbacks behave when a Global Namespace fails over between clusters, and the configuration required for worker-target endpoints: endpoint registry parity, replicated Namespaces, auto-forwarding, and a frontend httpPort plus advertised httpAddress on every cluster. Reorders "Build and use Nexus Services" above the new section. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel · 2026-07-17T01:06:49Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
temporal-documentation	Ready	Preview, Comment	Jul 21, 2026 6:37pm

github-actions · 2026-07-17T01:07:15Z

📖 Docs PR preview links

Production Deployment
- Self Hosted Guide
  - Temporal Nexus

- Capitalize Temporal proper nouns (Cluster, Namespace, Workflow, Worker, Task Queue, Endpoint, Nexus Operation) to match sibling multi-cluster docs. - Replace em-dashes with plain punctuation; drop "e.g."/"via" per style guide. - Add that caller and handler Namespaces can be active on different Clusters (per-Namespace active cluster), so cross-Cluster completion forwarding is a steady state, handled automatically once httpAddress is advertised. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- Move the target-type scope into a note that also mentions external-target Endpoints (--target-url) for completeness. - Vale pass: fix Worker casing, use contractions, split the long intro sentence, and use "automatic forwarding" instead of "auto-forwarding". Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…tion - Split auto-forwarding into its two required parts: the static dcRedirectionPolicy (defaults to no redirection) and the per-Namespace system.enableNamespaceNotActiveAutoForwarding dynamic config. - Trim the httpAddress step to the Nexus-specific delta (httpPort + httpAddress) and defer base clusterMetadata/rpcAddress setup to the Multi-Cluster Replication page it links to. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…ion entry - Link dcRedirectionPolicy to references/configuration, its canonical entry. - Clarify that the per-Cluster clusterInformation entry already contains the replication fields (enabled, rpcName, rpcAddress, initialFailoverVersion) and that httpAddress is added to it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Step 3 repeated the httpPort/httpAddress config already shown in Enable Nexus. Reference that section and keep only the multi-cluster delta: set them on every Cluster, plus the operator cluster upsert caveat. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Compress the 'What to expect on failover' list from five verbose bullets to four, folding the async-replication caveat into the permanent-loss point. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

It conflated the dynamic cluster-connection flow with the static-config instruction; httpAddress is set in static clusterInformation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- Explain system.enableNamespaceNotActiveAutoForwarding (per-Namespace, defaults to true) and note it has the opposite default of dcRedirectionPolicy. - Redraw the failover sequence so replication (not a failover-time handoff) carries state to Cluster B; remove the misleading A->B arrow. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- Remove semicolon from a sequence-diagram Note (mermaid treats ; as a statement separator, causing a render-time parse error). - Reword enableNamespaceNotActiveAutoForwarding as 'make sure it isn't turned off' since it defaults to true. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Drop the literal quotes and wrap the replication note across two lines so the Note-over box doesn't overflow. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

stephanos · 2026-07-17T20:30:48Z

+   default via `system.enableNamespaceNotActiveAutoForwarding` (per-Namespace
+   dynamic config).
+
+   Optionally, set the server's


I wasn't sure if this should be optional or recommended?

Not sure either TBH and not sure this information should go here, /self-hosted-guide/multi-cluster-replication seems like a better fit.

@bergundy I'll leave remove it and open a separate PR for /self-hosted-guide/multi-cluster-replication

Replace the manual jsdom global-copy loop with a one-line 'import global-jsdom/register'. (jsdom-global is unmaintained and doesn't expose the globals mermaid's box syntax needs; global-jsdom does.) Swap the direct jsdom devDependency for global-jsdom. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

stephanos · 2026-07-17T20:33:29Z

+// Set up a browser-like DOM before loading mermaid. mermaid.parse() uses DOM
+// APIs for some diagram syntaxes (for example a sequence diagram `box`) and
+// otherwise fails headless with "window is not defined".
+import 'global-jsdom/register';


This was needed to make the mermaid chart above work; the box is crucial to convey the topology clearly.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

bergundy

Approved, but please fix the experimental note before merging.

bergundy · 2026-07-21T14:32:26Z

 title:  Self-hosted Temporal Nexus
 sidebar_label: Temporal Nexus
-description: Use Nexus in your self-hosted Temporal Service.
+description: Use Nexus in your self-hosted Temporal Service, including across Global (multi-region) Namespaces.


I'm hesitant add this here. Multi-cluster support is experimental.

bergundy · 2026-07-21T14:33:29Z

 tags:
  - Self hosting
  - enable-nexus
+  - global-namespace


I think this terminology is outdated and we call this multi-cluster-replication now.

bergundy · 2026-07-21T14:34:15Z


 :::
+
+## Global Namespaces (multi-region failover)


Make a note that this is experimental and the mechanism here is likely to change.

bergundy · 2026-07-21T14:44:44Z

+   default via `system.enableNamespaceNotActiveAutoForwarding` (per-Namespace
+   dynamic config).
+
+   Optionally, set the server's


Not sure either TBH and not sure this information should go here, /self-hosted-guide/multi-cluster-replication seems like a better fit.

…step Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel Bot deployed to Preview July 17, 2026 01:07 View deployment

stephanos and others added 2 commits July 17, 2026 07:49

Update temporal-nexus.mdx

4ac3d82

vercel Bot deployed to Preview July 17, 2026 14:53 View deployment

vercel Bot deployed to Preview July 17, 2026 15:07 View deployment

vercel Bot deployed to Preview July 17, 2026 15:17 View deployment

vercel Bot deployed to Preview July 17, 2026 18:25 View deployment

Update temporal-nexus.mdx

b9b66c8

vercel Bot deployed to Preview July 17, 2026 18:28 View deployment

stephanos and others added 4 commits July 17, 2026 11:36

Tighten failover behavior bullets

1276f5e

Compress the 'What to expect on failover' list from five verbose bullets to four, folding the async-replication caveat into the permanent-loss point. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Shorten the httpAddress configuration step

87d8e8e

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Update temporal-nexus.mdx

88f2f08

vercel Bot deployed to Preview July 17, 2026 18:40 View deployment

stephanos and others added 2 commits July 17, 2026 11:41

Drop operator cluster upsert caveat from httpAddress step

bd91b56

It conflated the dynamic cluster-connection flow with the static-config instruction; httpAddress is set in static clusterInformation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Update temporal-nexus.mdx

af98ee2

vercel Bot deployed to Preview July 17, 2026 18:44 View deployment

vercel Bot deployed to Preview July 17, 2026 18:46 View deployment

stephanos and others added 2 commits July 17, 2026 11:47

Fix cut-off note in failover diagram

70e982c

Drop the literal quotes and wrap the replication note across two lines so the Note-over box doesn't overflow. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel Bot deployed to Preview July 17, 2026 18:49 View deployment

vercel Bot deployed to Preview July 17, 2026 18:50 View deployment

Update temporal-nexus.mdx

030e6e3

Update temporal-nexus.mdx

668317e

stephanos commented Jul 17, 2026

View reviewed changes

stephanos and others added 5 commits July 17, 2026 13:34

Update temporal-nexus.mdx

05e3d32

Clarify the advertise-httpAddress step

ff720fd

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Reword step 2 so the reader is the actor, not the section

6ee1921

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Update temporal-nexus.mdx

251345f

Update temporal-nexus.mdx

87a5226

vercel Bot deployed to Preview July 17, 2026 20:40 View deployment

stephanos marked this pull request as ready for review July 17, 2026 20:45

stephanos requested a review from a team as a code owner July 17, 2026 20:45

stephanos requested a review from bergundy July 17, 2026 20:45

bergundy approved these changes Jul 21, 2026

View reviewed changes

address feedback

b5a8ddc

vercel Bot deployed to Preview July 21, 2026 17:20 View deployment

rm

1138d01

vercel Bot deployed to Preview July 21, 2026 17:38 View deployment

stephanos mentioned this pull request Jul 21, 2026

Link to dcRedirectionPolicy for Multi-Cluster Replication #4931

Merged

stephanos changed the title ~~Document Nexus with Global Namespaces (multi-region failover) for self-hosted~~ Document Nexus with Multi-Cluster Replication for self-hosted Jul 21, 2026

Drop internal dynamic config flag name from Cross-Cluster forwarding …

3264f4d

…step Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

vercel Bot deployed to Preview July 21, 2026 18:00 View deployment

Duncanma approved these changes Jul 21, 2026

View reviewed changes

Merge branch 'main' into stephan/self-hosted-nexus-global-namespaces

a9ed756

Duncanma enabled auto-merge (squash) July 21, 2026 18:34

vercel Bot deployed to Preview July 21, 2026 18:37 View deployment

Duncanma merged commit 6dee623 into main Jul 21, 2026
13 checks passed

Duncanma deleted the stephan/self-hosted-nexus-global-namespaces branch July 21, 2026 18:37

stephanos mentioned this pull request Jul 21, 2026

Clarify Nexus failover behavior when the Handler Namespace fails over #4934

Draft

lennessyy mentioned this pull request Jul 21, 2026

fix(preview-links): honor custom frontmatter id when deriving doc URLs #4937

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Document Nexus with Multi-Cluster Replication for self-hosted#4906

Document Nexus with Multi-Cluster Replication for self-hosted#4906
Duncanma merged 58 commits into
mainfrom
stephan/self-hosted-nexus-global-namespaces

stephanos commented Jul 17, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Jul 17, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 17, 2026

Uh oh!

stephanos Jul 17, 2026 •

edited

Loading

Uh oh!

bergundy Jul 21, 2026

Uh oh!

stephanos Jul 21, 2026

Uh oh!

stephanos Jul 17, 2026 •

edited

Loading

Uh oh!

bergundy left a comment

Uh oh!

bergundy Jul 21, 2026

Uh oh!

bergundy Jul 21, 2026

Uh oh!

bergundy Jul 21, 2026

Uh oh!

bergundy Jul 21, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

stephanos commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 17, 2026

📖 Docs PR preview links

Uh oh!

stephanos Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bergundy Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

stephanos Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

stephanos Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bergundy left a comment

Choose a reason for hiding this comment

Uh oh!

bergundy Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

bergundy Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

bergundy Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

bergundy Jul 21, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

stephanos commented Jul 17, 2026 •

edited

Loading

vercel Bot commented Jul 17, 2026 •

edited

Loading

stephanos Jul 17, 2026 •

edited

Loading

stephanos Jul 17, 2026 •

edited

Loading